Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add some high level notes about rust-miniscript design #603

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

sanket1729
Copy link
Member

@sanket1729 sanket1729 commented Sep 27, 2023

Some notes to get people started. Still needs more details, but serves as a good start. In the long run, I believe, these can even be separate features with default on. This gives the option to people who really just want miniscript to use miniscript core without the policy/psbt/interpreter stuff.

@sanket1729
Copy link
Member Author

sanket1729 commented Sep 27, 2023

All the users are expected to interact with the library using the descriptor APIs. Raw miniscript should be used only if you know what you are doing.
* **Policy**(<span style="color:red">Red box</span>): This is the policy language for miniscript.
- It is a simple language which allows users to specify the policy for a descriptor. This simple user provided policy is referred as concrete policy. The miniscript compiler compiles this concrete policy into a descriptor.
- The policy also provides a semantic policy for analysis of descriptors and miniscript. Users can use the APIs in the module to analyze the descriptors and miniscript for various properties.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In 78c9df6:

I think we should say

- The policy module also provides a "semantic policy" for analysis of descriptors and miniscript. Unlike the concrete policy, which is implemented and used by other projects, the semantic policy is purely part of rust-miniscript. The APIs on this object can be used to analyze descriptors and miniscripts for various properties.

The main thing is to emphasize that there are actually two policy languages here; one is "the miniscript policy language" and the other is an analysis tool.

Arguably we should move the semantic policy out of the policy module ... and maybe rename it to Abstract which is what I originally wanted to do, but avoided because abstract (lowercase) is a reserved Rust keyword ... and maybe drop the FromStr and serde impls for it because you shouldn't ever be serializing a semantic policy.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, we move things so that semantic policy and concrete policy are not confused.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated.

Copy link
Member

@apoelstra apoelstra left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ACK e5640db

Copy link
Member

@tcharding tcharding left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just some minor things.


As of 10.0.0 rust-miniscript is roughly divided into following components:

* **Miniscript Core**(<span style="color:green">Green box</span>): This is the core of the library. It contains the core data structures and algorithms for miniscript and output descriptors.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* **Miniscript Core**(<span style="color:green">Green box</span>): This is the core of the library. It contains the core data structures and algorithms for miniscript and output descriptors.
* **Miniscript Core** (<span style="color:green">green box</span>): This is the core of the library. It contains the core data structures and algorithms for miniscript and output descriptors.

As of 10.0.0 rust-miniscript is roughly divided into following components:

* **Miniscript Core**(<span style="color:green">Green box</span>): This is the core of the library. It contains the core data structures and algorithms for miniscript and output descriptors.
All the users are expected to interact with the library using the descriptor APIs. Raw miniscript should be used only if you know what you are doing.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
All the users are expected to interact with the library using the descriptor APIs. Raw miniscript should be used only if you know what you are doing.
All users are expected to interact with the library using the descriptor APIs. Raw miniscript should be used only if you really know what you are doing.


* **Miniscript Core**(<span style="color:green">Green box</span>): This is the core of the library. It contains the core data structures and algorithms for miniscript and output descriptors.
All the users are expected to interact with the library using the descriptor APIs. Raw miniscript should be used only if you know what you are doing.
* **Policy**(<span style="color:red">Red box</span>): This module consists of _two_ separate policy languages with different purposes:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* **Policy**(<span style="color:red">Red box</span>): This module consists of _two_ separate policy languages with different purposes:
* **Policy** (<span style="color:red">red box</span>): This module consists of _two_ separate policy languages with different purposes:

- _Concrete Policy_: Concrete policy is a simple language which allows users to specify the policy for a descriptor. The miniscript compiler compiles this concrete policy into a descriptor.
- _Semantic Policy_: The policy module also provides a "semantic policy" for analysis of descriptors and miniscript. Unlike the concrete policy, which is implemented and used by other projects, the semantic policy is purely part of rust-miniscript. The APIs on this object can be used to analyze descriptors and miniscripts for various properties.

* **Psbt**(<span style="color:blue">Blue box</span>): Psbt support for descriptors. Provides several new extension APIs to interact for miniscript descriptors in a psbt including finalizer, planning, signing, descriptor updates, etc.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* **Psbt**(<span style="color:blue">Blue box</span>): Psbt support for descriptors. Provides several new extension APIs to interact for miniscript descriptors in a psbt including finalizer, planning, signing, descriptor updates, etc.
* **Psbt** (<span style="color:blue">blue box</span>): Psbt support for descriptors. Provides several new extension APIs to interact for miniscript descriptors in a psbt including finalizer, planning, signing, descriptor updates, etc.

- _Semantic Policy_: The policy module also provides a "semantic policy" for analysis of descriptors and miniscript. Unlike the concrete policy, which is implemented and used by other projects, the semantic policy is purely part of rust-miniscript. The APIs on this object can be used to analyze descriptors and miniscripts for various properties.

* **Psbt**(<span style="color:blue">Blue box</span>): Psbt support for descriptors. Provides several new extension APIs to interact for miniscript descriptors in a psbt including finalizer, planning, signing, descriptor updates, etc.
* **Interpreter**(<span style="color:yellow">Yellow box</span>): Script Interpreter for miniscript. It also provides APIs to figure out the satisfied constraints for a given transaction input. Useful for detecting which spend path the transaction output was spend with, as in the case of watchtowers or general monitoring, block explorers, etc.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* **Interpreter**(<span style="color:yellow">Yellow box</span>): Script Interpreter for miniscript. It also provides APIs to figure out the satisfied constraints for a given transaction input. Useful for detecting which spend path the transaction output was spend with, as in the case of watchtowers or general monitoring, block explorers, etc.
* **Interpreter** (<span style="color:yellow">yellow box</span>): Script interpreter for miniscript. It also provides APIs to figure out the satisfied constraints for a given transaction input. Useful for detecting which spend path the transaction output was spent with, as in the case of watchtowers or general monitoring, block explorers, etc.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants